HyperKitty MCP Server

A Model Context Protocol (MCP) server that provides read-only access to HyperKitty, the web-based email archive component of Mailman 3.

Features

• Read-Only Archive Access: Complete access to email archives through HyperKitty's REST API
• Private Archives Support: Access private archives with credential-based authentication
• Dynamic Server Switching: Connect to any HyperKitty installation by simply mentioning the URL in chat
• 9 Tools: 7 archive tools + 2 server management tools

Installation

Add the MCP server to your AI assistant configuration file:

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor IDE:

• Workspace-specific (recommended): .cursor/mcp.json in your project root
• Global (macOS/Linux): ~/.cursor/config.json
• Global (Windows): %USERPROFILE%\.cursor\config.json

Add this configuration:

{
  "mcpServers": {
    "hyperkitty": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "registry.gitlab.com/thenewit/hyperkitty-mcp"]
    }
  }
}

To access private archives, mount a credentials file (see Credentials Configuration):

{
  "mcpServers": {
    "hyperkitty": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -v ~/.hyperkitty-mcp/credentials.yaml:/home/hyperkitty/.hyperkitty-mcp/credentials.yaml:ro registry.gitlab.com/thenewit/hyperkitty-mcp"
      ]
    }
  }
}

Configuration

Connecting to a Server

Specify the HyperKitty server in your chat:

"Show me mailing lists on https://lists.mailman3.com/hyperkitty"

The server will connect to the specified URL and stay connected for subsequent commands. You can switch to a different server at any time by mentioning a new URL.

To auto-connect to a specific server on startup, set the HYPERKITTY_BASE_URL environment variable:

{
  "mcpServers": {
    "hyperkitty": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "HYPERKITTY_BASE_URL=https://lists.mailman3.com/hyperkitty",
        "registry.gitlab.com/thenewit/hyperkitty-mcp"
      ]
    }
  }
}

Environment Variables

• HYPERKITTY_BASE_URL: (Optional) Base URL of the HyperKitty instance. If set, auto-connects on startup.
• HYPERKITTY_USERNAME: Username for Django-allauth authentication (fallback for all servers)
• HYPERKITTY_PASSWORD: Password for Django-allauth authentication (fallback for all servers)
• HYPERKITTY_LOGIN_URL: Login URL path relative to site root (default: /accounts/login/). Override if your Django-allauth is mounted at a different path.
• HYPERKITTY_TIMEOUT: Request timeout in seconds (default: 30.0)
• HYPERKITTY_VERIFY_SSL: Whether to verify SSL certificates (default: true)

Credentials Configuration

For secure credential management across multiple HyperKitty servers, create a credentials file:

Location (checked in order):

1. $HYPERKITTY_CREDENTIALS_PATH (environment variable)
2. ~/.hyperkitty-mcp/credentials.yaml
3. $XDG_CONFIG_HOME/hyperkitty-mcp/credentials.yaml

Format:

# ~/.hyperkitty-mcp/credentials.yaml
credentials:
  # Exact domain match
  lists.mailman3.com:
    username: user@example.com
    password: mypassword
  
  # Another server
  lists.mycompany.com:
    username: admin@mycompany.com
    password: secret123
  
  # Wildcard pattern for internal servers
  "*.internal.corp":
    username: service-account
    password: internal-secret

Credential Lookup Order:

1. Credentials file (by domain match)
2. Environment variables (HYPERKITTY_USERNAME, HYPERKITTY_PASSWORD)
3. Public-only access (no authentication)

Performance Configuration

See Performance Configuration for tuning options.

Available Tools

Server Management Tools (2 tools)

1. set_server: Connect to a HyperKitty server

   • Parameters: base_url (e.g., https://lists.mailman3.com/hyperkitty)
   • Automatically looks up credentials from the credentials file
   • Returns connection status (authenticated or public-only)

2. get_current_server: Show current connection info

   • Returns the current server URL and authentication status
   • Does NOT expose credentials

Archive Tools (7 tools)

All archive tools are read-only and require a server to be connected first:

1. list_mailing_lists: List archived mailing lists (with pagination)

   • Note: Only returns lists with PUBLIC archives. Private archives are excluded by HyperKitty.

2. get_list_details: Get detailed archive information for a list

   • Can also be used to check if archives exist (returns 404 error if no archives)
   • Works for both public and private archives (private archives require authentication)
   • Returns comprehensive metadata including post count, archive URL, creation date, etc.

3. get_threads: Get discussion threads from a list (with pagination)

   • Returns threads with subject, authors, dates, reply counts
   • Use pagination for lists with many threads

4. get_thread_emails: Get emails in a thread (with pagination)

   • Returns individual messages within a thread
   • Includes full content, headers, and metadata

5. get_email: Get a specific email message

   • Retrieve single email by message ID hash
   • Includes full content, headers, attachments

6. download_attachment: Download an attachment from an email

   • Downloads binary attachment content
   • Returns base64-encoded content with metadata (filename, content type, size, encoding)
   • Parameters: list_address, message_id_hash, attachment_counter
   • Use get_email first to get attachment metadata and counter numbers

7. list_tags: List all tags used in archives

   • Returns tags applied to threads across all lists

Usage Examples

Interact with HyperKitty archives using natural language:

Connect to a server (specify once, stays connected for subsequent commands):

"Show me mailing lists on https://lists.mailman3.com/hyperkitty"

Browse archives (uses the currently connected server):

"Get archive details for announcements@mailman3.com"
"Show me the latest 10 threads from announcements@mailman3.com"
"Get all emails in that thread"
"Download the first attachment from that email"
"List all tags used in HyperKitty"

Switch to another server:

"Now check https://lists.mycompany.com/archives"
"Show me all mailing lists there"

Check current connection:

"Which HyperKitty server am I connected to?"

Development

Building Docker Image

git clone https://gitlab.com/TheNewIT/hyperkitty-mcp.git
cd hyperkitty-mcp
docker build -t hyperkitty-mcp .

Then use hyperkitty-mcp instead of registry.gitlab.com/thenewit/hyperkitty-mcp in your configuration.

From Source

git clone https://gitlab.com/TheNewIT/hyperkitty-mcp.git
cd hyperkitty-mcp
pip install -e .

Use direct Python execution in your MCP configuration:

{
  "mcpServers": {
    "hyperkitty": {
      "command": "python",
      "args": ["-m", "hyperkitty_mcp"]
    }
  }
}

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests with verbose output
pytest -v

# Run tests with coverage
pytest --cov=src/hyperkitty_mcp --cov-report=html

Code Formatting

# Format code with black
black src/ tests/

# Check code style with ruff
ruff check src/ tests/

# Auto-fix issues
ruff check --fix src/ tests/

License

GNU General Public License v3 or later - See LICENSE file for details.